---
title: "Installing the EJAM R package"
description: "1. Installing the EJAM R package"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Installing the EJAM R package}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r developernote, eval=FALSE, echo= FALSE, include = FALSE}
#  *>>>>>>>>>> Developer note: vignettes need to be tested/edited/rebuilt regularly <<<<<<<<<<<*
#    - **See ?pkgdown::build_site** and script in EJAM/data-raw/- EJAM uses the pkgdown R package to build help and articles/ vignettes as web pages
```

```{r SETUP_default_eval_or_not, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
knitr::opts_chunk$set(eval = FALSE)
# https://r-pkgs.org/vignettes.html
```

```{r libraryEJAM, eval = FALSE, echo= FALSE, include= FALSE}
# rm(list = ls())
# golem::detach_all_attached()
# 
library(EJAM)
# dataload_from_pins('all') # varnames = all  currently means all these:
dataload_from_pins(
  c("blockwts", "blockpoints", "blockid2fips", "quaddata", 
    "bgej", "bgid2fips",
    "frs", "frs_by_programid", "frs_by_naics", "frs_by_sic", "frs_by_mact")
)

##################################### #
if (!exists("blockid2fips")) {
  cat("warning: blockid2fips not available\n")
  # *** temporary workaround if building vignette on 1 particular machine
  here <- "~/../Downloads/EJAMbigfiles"
  varnames <- c('blockwts', 'blockpoints', 'blockid2fips', "quaddata",
                'bgej','bgid2fips', 
                'frs', 'frs_by_programid', 'frs_by_naics', "frs_by_sic", "frs_by_mact")
  fnames <- paste0(varnames, ".arrow")
  localpaths  <- paste0(here, '/', fnames)
  for (i in 1:length(varnames)) {assign(varnames[i], arrow::read_ipc_file(file = localpaths[i]))}
  rm(here, varnames, fnames, localpaths)
}
##################################### #

indexblocks()
```

EJAM is not only a web app built in shiny R, it is also an R package, using the [golem](https://thinkr-open.github.io/golem/ "https://thinkr-open.github.io/golem/"){.uri target="_blank" rel="noreferrer noopener"} framework.

The package can be installed from a github repository. It can be installed locally as an R package, and the data or functions can be used outside of the shiny app interface, if you want to reuse data or code, or want to do customized analysis or explore the data in R.

## How to install

### Try this first (if you just want to use the package, not clone & edit source code)

```{r install_github_main, eval=FALSE, include=TRUE}
options(timeout = 300) # Just in case the download takes longer than 60 seconds
if (!require(remotes)) {install.packages("remotes")}

remotes::install_github("USEPA/EJAM-open", dependencies = TRUE)

library(EJAM)
```

You can also install it with source references and tests like this:
```{r install_github_keepsource, eval=FALSE, include=TRUE}
remotes::install_github("USEPA/EJAM-open", dependencies = TRUE,
          INSTALL_opts = c("--with-keep.source", "--install-tests"))
```

If install_github does not work, you can try something like this:
```{r install_url, eval=FALSE, include=TRUE}

x <- "https://github.com/USEPA/EJAM-open/archive/refs/tags/v2.32-EJAM-open.tar.gz"

remotes::install_url(url = x, dependencies = TRUE, auth_token = "")
```

------------------------------------------------------------------------

### if you need the full source code or want to build/install in RStudio on your own

The EJAM package is available as one of the [USEPA github](https://github.com/USEPA/EJAM-open "github.com/USEPA/EJAM-open"){.uri target="_blank" rel="noreferrer noopener"} repositories (not on CRAN).

Options for getting the source package:

a.  One way to get the source package is that in RStudio you can click New Project, Version Control, Git, and enter the repository URL. It will download the full source package, which has additional files related to development that you do not need if you just want to use the package.

b.  Yet another way to get the full source package is to use a browser to go to the repository page, such as [USEPA github](https://github.com/USEPA/EJAM-open "github.com/USEPA/EJAM-open"){.uri target="_blank" rel="noreferrer noopener"} and then click the green "Code" button, and download and unzip the zip file that contains the package.

c.  A third way is to Clone or Fork the package via GitHub Desktop or from the GitHub site.

Regardless of how you got the full source code, you would then need to build/install the package from source on your computer using RStudio (using the Build menu) or using the devtools package, for example.

### for a repository that is non-public (internal or private, for EPA only)

If a USEPA github repository is not public, you need to be inside EPA's network (e.g., via VPN) and also need to get a personal access token (PAT):

1.  create a GitHub personal access token with at least 'repo scope' which you can do at <https://github.com/settings/tokens>

-   For background on this, see [https://usethis.r-lib.org/articles/git-credentials.html#tldr-use-https-2fa-and-a-github-personal-access-token](https://usethis.r-lib.org/articles/git-credentials.html#tldr-use-https-2fa-and-a-github-personal-access-token){.uri target="_blank" rel="noreferrer noopener"}

-   Go to [https://github.com/settings/tokens](https://github.com/settings/tokens){.uri target="_blank" rel="noreferrer noopener"} and select Tokens (classic) on the left-hand side. Then click 'Generate New Token' -\> Generate new token (classic).

-   Give it a name and select all boxes under repo scope. Scroll down and click 'Generate Token'.

2.  save GitHub credentials via Rstudio

-   one-time login: from the console, run `credentials::set_github_pat()`. Paste in your PAT to the login popup under 'Token'. This will save the PAT in your GITHUB_PAT environmental variable, where `remotes::install_github()` or `devtools::install_github()` will by default look for it.

3.  Try to install the package using `devtools::install_github()`

#### CRAN packages needed (dependencies)

EJAM needs a number of other packages to be installed that are available from CRAN. Trying to load and attach EJAM with require(EJAM) or library(EJAM) will alert you to those other packages you need to install if you don't already have them. The list of CRAN packages needed is in the `DESCRIPTION` file in the R package source code root folder (as can be found in the code repository). Note some are in Suggests and you might want to install those as well -- using dependencies=T in install_github() or install_url() will make sure of that.

## Initialize: load/attach package

Once the right R packages are installed, to use EJAM in the console you can start by loading and attaching the package, using library or require. It should automatically download some data and build an index.

```{r libraryejam, eval=FALSE}

require(EJAM)

```

**That should be all you need to do.**

------------------------------------------------------------------------

Just in case you need more details on how that works, the following describes the code used by the package to get the data and build an index.

### Details on the automatic data downloads

To work in the RStudio console, EJAM needs some datasets not stored as part of the package. However, they already should be downloaded and loaded into memory automatically as soon as you use `require(EJAM)`. 

Typically you would not need to download any datasets yourself, because EJAM just downloads these when the app starts (technically, when the R package is attached) (or only as needed in the case of certain datasets that are not always needed). Some datasets are installed along with the package, such as the [blockgroupstats] data. But large files like "[blockpoints]" are stored on a "pins board" server and EJAM downloads them from there. You might want your own local copies, though, for these reasons:
 
Attaching the package actually checks for copies in memory first (e.g., `exists("quaddata", envir = globalenv())`), then local disk (using [dataload_from_local()] looking in the data folder of the (source or installed) package, as defined by `EJAM:::app_sys()` which is just a wrapper for `system.file()`), then finally tries to download any still needed, using [dataload_from_pins()] for example.

### Details on the indexing of blocks

EJAM also needs to build the index of about 8 million US block locations (one internal point for each block), which takes a few seconds. EJAM does this automatically when attached via `require(EJAM)` or `library(EJAM)`, by creating an object called [localtree](../reference/localtree.html) based on the [quaddata](../reference/quaddata.html) object obtained as mentioned above. Some functions check for it and try to build the index on the fly if it is missing. You can also (re)build it manually:

```{r indexblocks, eval=FALSE}
indexblocks()
```
